{ { content }}
本文共 20922 字，大约阅读时间需要 69 分钟。
In this article, we'll compare the nuances of creating themes for the top two static site generators.
在本文中，我们将比较为前两个静态网站生成器创建主题的细微差别。
I recently took on the task of creating a documentation site theme for two projects. Both projects needed the same basic features, but one uses Jekyll while the other uses Hugo.
我最近承担了为两个项目创建文档站点主题的任务。 两个项目都需要相同的基本功能，但是一个使用Jekyll，另一个使用Hugo。
In typical developer rationality, there was clearly only one option. I decided to create the same theme in both frameworks, and to give you, dear reader, a side-by-side comparison.
按照典型的开发人员理性，显然只有一种选择。 我决定在两个框架中创建相同的主题，并为您提供亲爱的读者并排比较。
This post isn’t a comprehensive theme-building guide, but is rather intended to familiarize you with the process of building a theme in either generator. Here's what we'll cover:
这篇文章不是全面的主题构建指南，而是旨在使您熟悉在任一生成器中构建主题的过程。 这是我们要介绍的内容：
Creating a top-level menu with the pages object
使用pages对象创建顶层菜单
Here’s a crappy wireframe of the theme I’m going to create.
这是我要创建的主题的wire脚线框。
If you’re planning to build-along, it may be helpful to serve the theme locally as you build it – and both generators offer this functionality. For Jekyll, run jekyll serve, and for Hugo, hugo serve.
如果您打算同时构建，则在构建主题时在本地提供主题可能会有所帮助–并且两个生成器都提供此功能。 对于Jekyll，请运行jekyll serve ；对于Hugo，请使用雨果hugo serve 。
There are two main elements: the main content area, and the all-important sidebar menu. To create them, you’ll need template files that tell the site generator how to generate the HTML page. To organize theme template files in a sensible way, you first need to know what directory structure the site generator expects.
有两个主要元素：主要内容区域和非常重要的侧边栏菜单。 要创建它们，您将需要模板文件，这些文件告诉网站生成器如何生成HTML页面。 要以一种明智的方式组织主题模板文件，您首先需要知道站点生成器期望的目录结构。
Jekyll supports gem-based themes, which users can install like any other Ruby gems. This method hides theme files in the gem, so for the purposes of this comparison, we aren’t using gem-based themes.
Jekyll支持基于gem的主题，用户可以像安装其他任何Ruby gem一样进行安装。 此方法将主题文件隐藏在gem中，因此出于比较目的，我们未使用基于gem的主题。
When you run jekyll new-theme <name>, Jekyll will scaffold a new theme for you. Here’s what those files look like:
当您运行jekyll new-theme <name> ，Jekyll将为您架设一个新主题。 这些文件如下所示：
.├── assets├── Gemfile├── _includes├── _layouts│ ├── default.html│ ├── page.html│ └── post.html├── LICENSE.txt├── README.md├── _sass└──.gemspec
The directory names are appropriately descriptive. The _includes directory is for small bits of code that you reuse in different places, in much the same way you’d put butter on everything. (Just me?)
目录名称具有适当的描述性。 _includes目录用于在不同地方重复使用的少量代码，几乎就像在所有内容上加黄油一样。 (只有我？)
The _layouts directory contains templates for different types of pages on your site. The _sass folder is for files used to build your site’s stylesheet.
_layouts目录包含网站上不同类型页面的模板。 _sass文件夹用于用于构建网站样式表的文件。
You can scaffold a new Hugo theme by running hugo new theme <name>. It has these files:
您可以通过运行hugo new theme <name>来搭建一个新的Hugo主题。 它具有以下文件：
.├── archetypes│ └── default.md├── layouts│ ├── 404.html│ ├── _default│ │ ├── baseof.html│ │ ├── list.html│ │ └── single.html│ ├── index.html│ └── partials│ ├── footer.html│ ├── header.html│ └── head.html├── LICENSE├── static│ ├── css│ └── js└── theme.toml
You can see some similarities. Hugo’s page template files are tucked into layouts/. Note that the _default page type has files for a list.html and a single.html.
您会看到一些相似之处。 Hugo的页面模板文件被塞入layouts/ 。 请注意， _default页面类型具有list.html和single.html 。
Unlike Jekyll, Hugo uses these specific file names to distinguish between (like a page with links to all your blog posts on it) and (like one of your blog posts). The layouts/partials/ directory contains the buttery reusable bits, and stylesheet files have a spot picked out in static/css/.
与Jekyll不同，Hugo使用这些特定的文件名来区分 (例如带有指向您所有博客文章链接的页面)和 (例如您的博客文章之一)。 layouts/partials/目录包含可重复使用的黄油，样式表文件的位置在static/css/ 。
These directory structures aren’t set in stone, as both site generators allow some measure of customization. For example, Jekyll lets you define , and Hugo makes use of . These features let you organize your content multiple ways, but for now, let's look at where to put some simple pages.
这些目录结构并不是一成不变的，因为两个站点生成器都允许某种程度的自定义。 例如，Jekyll允许您定义 ，而Hugo利用 。 这些功能使您可以通过多种方式组织内容，但现在，让我们看一下放置一些简单页面的位置。
To create a site menu that looks like this:
要创建一个如下所示的站点菜单：
Introduction Getting Started Configuration DeployingAdvanced Usage All Configuration Settings Customizing Help and Support
You’ll need two sections (“Introduction” and “Advanced Usage”) containing their respective subsections.
您将需要两个部分(“简介”和“高级用法”)，分别包含各自的小节。
Jekyll isn’t strict with its content location. It expects pages in the root of your site, and will build whatever’s there. Here’s how you might organize these pages in your Jekyll site root:
Jekyll对其内容位置并不严格。 它期望页面位于您网站的根目录中，并将构建任何内容。 您可以按照以下方式在Jekyll网站根目录中组织这些页面：
.├── 404.html├── assets├── Gemfile├── _includes├── index.markdown├── intro│ ├── config.md│ ├── deploy.md│ ├── index.md│ └── quickstart.md├── _layouts│ ├── default.html│ ├── page.html│ └── post.html├── LICENSE.txt├── README.md├── _sass├──.gemspec└── usage ├── customizing.md ├── index.md ├── settings.md └── support.md
You can change the location of the site source in your .
您可以在更改站点源的位置。
In Hugo, all rendered content is expected in the content/ folder. This prevents Hugo from trying to render pages you don’t want, such as 404.html, as site content. Here’s how you might organize your content/ directory in Hugo:
在Hugo中，所有呈现的内容都应在content/文件夹中。 这样可以防止Hugo尝试将不需要的页面(例如404.html呈现为网站内容。 这是您在Hugo中组织content/目录的方式：
.├── _index.md├── intro│ ├── config.md│ ├── deploy.md│ ├── _index.md│ └── quickstart.md└── usage ├── customizing.md ├── _index.md ├── settings.md └── support.md
To Hugo, _index.md and index.md mean different things. It can be helpful to know what kind of you want for each section: Leaf, which has no children, or Branch.
对于Hugo来说， _index.md和index.md含义不同。 了解每个部分需要哪种可能会有所帮助：无子级的Leaf或Branch。
Now that you have some idea of where to put things, let’s look at how to build a page template.
现在您已经知道了将内容放置在哪里，让我们看看如何构建页面模板。
Jekyll page templates are built with the . It uses braces to output variable content to a page, such as the page’s title: { { page.title }}.
Jekyll页面模板是使用构建的。 它使用花括号将可变内容输出到页面，例如页面的标题： { { page.title }} 。
Hugo’s templates also use braces, but they’re built with . The syntax is similar, but different: { { .Title }}.
Hugo的模板也使用花括号，但它们是使用构建的。 语法相似，但不同： { { .Title }} 。
Both Liquid and Go Templates can handle logic. Liquid uses tags syntax to denote logic operations:
Liquid和Go模板都可以处理逻辑。 Liquid使用标签语法来表示逻辑运算：
{% if user %} Hello { { user.name }}!{% endif %} And Go Templates places its functions and arguments in its braces syntax:
Go Templates将其功能和参数放在其大括号语法中：
{ { if .User }} Hello { { .User }}!{ { end }} Templating languages allow you to build one skeleton HTML page, then tell the site generator to put variable content in areas you define. Let’s compare two possible default page templates for Jekyll and Hugo.
模板语言允许您构建一个框架HTML页面，然后告诉网站生成器将可变内容放入您定义的区域。 让我们比较一下Jekyll和Hugo的两个可能的default页面模板。
Jekyll’s scaffold default theme is bare, so we’ll look at their starter theme . Here’s _layouts/default.html in Jekyll (Liquid):
Jekyll的脚手架default主题为裸色，因此我们将看看他们的入门主题 。 这是Jekyll(液体)中的_layouts/default.html ：
{%- include head.html -%} {%- include header.html -%} { { content }} {%- include footer.html -%} Here’s Hugo’s scaffold theme layouts/_default/baseof.html (Go Templates):
这是Hugo的脚手架主题layouts/_default/baseof.html (转到模板)：
{ {- partial "head.html" . -}} { {- partial "header.html" . -}} { {- block "main" . }}{ {- end }} { {- partial "footer.html" . -}} Different syntax, same idea. Both templates pull in reusable bits for head.html, header.html, and footer.html. These show up on a lot of pages, so it makes sense not to have to repeat yourself.
不同的语法，相同的想法。 这两个模板都为head.html ， header.html和footer.html head.html了可重用的位。 这些内容显示在很多页面上，因此不必重复自己就很有意义。
Both templates also have a spot for the main content, though the Jekyll template uses a variable ({ { content }}) while Hugo uses a block ({ {- block "main" . }}{ {- end }}). are just another way Hugo lets you define reusable bits.
尽管Jekyll模板使用变量( { { content }} )，而Hugo使用块( { {- block "main" . }}{ {- end }} )，但这两个模板也都具有主要内容。 只是Hugo允许您定义可重用位的另一种方式。
Now that you know how templating works, you can build the sidebar menu for the theme.
现在您知道模板的工作原理，您可以为主题构建侧边栏菜单。
pages对象创建顶层菜单 (Creating a top-level menu with the pages object)You can programmatically create a top-level menu from your pages. It will look like this:
您可以以编程方式从页面创建顶层菜单。 它看起来像这样：
IntroductionAdvanced Usage
Let’s start with Jekyll. You can display links to site pages in your Liquid template by iterating through the site.pages object that Jekyll provides and building a list:
让我们从杰基尔开始。 您可以通过遍历Jekyll提供的site.pages对象并构建一个列表，在Liquid模板中显示指向网站页面的链接：
This returns all of the site’s pages, including all the ones that you might not want, like 404.html. You can filter for the pages you actually want with a couple more tags, such as conditionally including pages if they have a section: true parameter set:
这将返回网站的所有页面，包括您可能不需要的所有页面，例如404.html 。 您可以使用更多标签过滤实际所需的页面，例如，如果页面具有section: true ，则有条件地包括这些页面section: true参数集：
You can achieve the same effect with slightly less code in Hugo. Loop through Hugo’s .Pages object using Go Template’s :
您可以在Hugo中使用更少的代码来达到相同的效果。 使用Go Template的遍历Hugo的.Pages对象：
This template uses the .Pages object to return all the top-level pages in content/ of your Hugo site. Since Hugo uses a specific folder for the site content you want rendered, there’s no additional filtering necessary to build a simple menu of site pages.
此模板使用.Pages对象返回Hugo网站content/的所有顶级页面。 由于Hugo为您要呈现的网站内容使用特定的文件夹，因此无需额外的筛选即可构建简单的网站页面菜单。
Both site generators can use a separately defined data list of links to render a menu in your template. This is more suitable for creating nested links, like this:
两个站点生成器都可以使用单独定义的链接数据列表来在模板中呈现菜单。 这更适合创建嵌套链接，如下所示：
Introduction Getting Started Configuration DeployingAdvanced Usage All Configuration Settings Customizing Help and Support
Jekyll supports in a few formats, including YAML. Here’s the definition for the menu above in _data/menu.yml:
Jekyll支持几种格式的 ，包括YAML。 这是_data/menu.yml上面菜单的定义：
section: - page: Introduction url: /intro subsection: - page: Getting Started url: /intro/quickstart - page: Configuration url: /intro/config - page: Deploying url: /intro/deploy - page: Advanced Usage url: /usage subsection: - page: Customizing url: /usage/customizing - page: All Configuration Settings url: /usage/settings - page: Help and Support url: /usage/support
Here’s how to render the data in the sidebar template:
以下是在侧边栏模板中呈现数据的方法：
{% for a in site.data.menu.section %}{ { a.page }} This method allows you to build a custom menu, two nesting levels deep. The nesting levels are limited by the for loops in the template. For a recursive version that handles further levels of nesting, see .
此方法使您可以构建一个自定义菜单，深两个嵌套级别。 嵌套级别受模板中的for循环限制。 有关可处理更多嵌套级别的递归版本，请参阅 。
Hugo does something similar with its . You can define menu links in your , and even add useful properties that Hugo understands, like weighting. Here’s a definition of the menu above in config.yaml:
雨果(Hugo)的做类似的事情。 您可以在定义菜单链接，甚至可以添加Hugo可以理解的有用属性，例如权重。 这是上面config.yaml菜单的定义：
sectionPagesMenu: mainmenu: main: - identifier: intro name: Introduction url: /intro/ weight: 1 - name: Getting Started parent: intro url: /intro/quickstart/ weight: 1 - name: Configuration parent: intro url: /intro/config/ weight: 2 - name: Deploying parent: intro url: /intro/deploy/ weight: 3 - identifier: usage name: Advanced Usage url: /usage/ - name: Customizing parent: usage url: /usage/customizing/ weight: 2 - name: All Configuration Settings parent: usage url: /usage/settings/ weight: 1 - name: Help and Support parent: usage url: /usage/support/ weight: 3
Hugo uses the identifier, which must match the section name, along with the parent variable to handle nesting. Here’s how to render the menu in the sidebar template:
Hugo使用identifier (必须与节名称匹配)以及parent变量来处理嵌套。 以下是在侧边栏模板中呈现菜单的方法：
The range function iterates over the menu data, and Hugo’s .Children variable handles nested pages for you.
range函数遍历菜单数据，Hugo的.Children变量为您处理嵌套页面。
With your menu in your reusable sidebar bit (_includes/sidebar.html for Jekyll and partials/sidebar.html for Hugo), you can add it to the default.html template.
将菜单放在可重复使用的侧边栏位中(对于Jekyll为_includes/sidebar.html ，对于Hugo为partials/sidebar.html )，可以将其添加到default.html模板中。
In Jekyll:
在杰基尔：
{%- include head.html -%} {%- include sidebar.html -%} {%- include header.html -%} { { content }} {%- include footer.html -%} In Hugo:
在雨果：
{ {- partial "head.html" . -}} { {- partial "sidebar.html" . -}} { {- partial "header.html" . -}} { {- block "main" . }}{ {- end }} { {- partial "footer.html" . -}} When the site is generated, each page will contain all the code from your sidebar.html.
生成网站后，每个页面都将包含sidebar.html所有sidebar.html 。
Both site generators accept Sass for creating CSS stylesheets. Jekyll , and Hugo uses . Both options have some quirks.
两个站点生成器都接受Sass创建CSS样式表。 Jekyll ，Hugo使用 。 两种选择都有一些怪癖。
To process a Sass file in Jekyll, create your style definitions in the _sass directory. For example, in a file at _sass/style-definitions.scss:
要在Jekyll中处理Sass文件，请在_sass目录中创建样式定义。 例如，在_sass/style-definitions.scss的文件中：
$background-color: #eef !default;$text-color: #111 !default;body { background-color: $background-color; color: $text-color;} Jekyll won’t generate this file directly, as it only processes files with front matter. To create the end-result filepath for your site’s stylesheet, use a placeholder with empty front matter where you want the .css file to appear. For example, assets/css/style.scss. In this file, simply import your styles:
Jekyll不会直接生成此文件，因为它仅处理前端文件。 要为您网站的样式表创建最终结果文件路径，请在您希望显示.css文件的位置使用带空的占位符的占位符。 例如， assets/css/style.scss 。 在此文件中，只需导入样式：
------@import "style-definitions";
This rather hackish configuration has an upside: you can use Liquid template tags and variables in your placeholder file. This is a nice way to allow users to set variables from the site _config.yml, for example.
这种颇为骇人听闻的配置有一个好处：您可以在占位符文件中使用Liquid模板标签和变量。 例如，这是允许用户从站点_config.yml设置变量的好方法。
The resulting CSS stylesheet in your generated site has the path /assets/css/style.css. You can link to it in your site’s head.html using:
生成的网站中生成CSS样式表的路径为/assets/css/style.css 。 您可以使用以下方法在您网站的head.html链接到该网站：
Hugo uses to process Sass to CSS. You can achieve this by using Hugo’s asset processing function, resources.ToCSS, which expects a source in the assets/ directory. It takes the SCSS file as an argument.
Hugo使用将Sass转换为CSS。 您可以通过使用Hugo的资产处理功能resources.ToCSS来实现这一目标，该功能需要有一个assets/目录。 它使用SCSS文件作为参数。
With your style definitions in a Sass file at assets/sass/style.scss, here’s how to get, process, and link your Sass in your theme’s head.html:
将您的样式定义保存在assets/sass/style.scss中的Sass文件中，以下是在主题的head.html获取，处理和链接Sass的head.html ：
{ { $style := resources.Get "/sass/style.scss" | resources.ToCSS }} Hugo asset processing , which you may not have by default. You can get extended Hugo from the .
Hugo资产处理 ，默认情况下您可能没有。 您可以从获取扩展的Hugo。
Before your site generator can build your site, it needs a configuration file to set some necessary parameters. Configuration files live in the site root directory. Among other settings, you can declare the name of the theme to use when building the site.
在站点生成器可以构建站点之前，它需要一个配置文件来设置一些必要的参数。 配置文件位于站点根目录中。 在其他设置中，您可以声明在构建网站时使用的主题名称。
Here’s a minimal _config.yml for Jekyll:
这是Jekyll的最小_config.yml ：
title: Your awesome titledescription: >- # this means to ignore newlines until "baseurl:" Write an awesome description for your new site here. You can edit this line in _config.yml. It will appear in your document head meta (for Google search results) and in your feed.xml site description.baseurl: "" # the subpath of your site, e.g. /blogurl: "" # the base hostname & protocol for your site, e.g. http://example.comtheme: # for gem-based themesremote_theme: # for themes hosted on GitHub, when used with GitHub Pages
With remote_theme, any with sites hosted on GitHub Pages.
使用remote_theme ， 任何与托管在GitHub Pages上的站点 。
Jekyll has a , so any parameters added to your configuration file will override the defaults. Here are .
Jekyll具有 ，因此添加到配置文件中的任何参数都将覆盖默认设置。 这是 。
Here’s a minimal example of Hugo’s config.yml:
这是Hugo的config.yml的一个最小示例：
baseURL: https://example.com/ # The full domain your site will live atlanguageCode: en-ustitle: Hugo Docs Sitetheme: # theme name
Hugo makes no assumptions, so if a necessary parameter is missing, you’ll see a warning when building or serving your site. Here are .
Hugo不做任何假设，因此，如果缺少必要的参数，则在构建或服务您的网站时会看到警告。 这是 。
Both generators build your site with a command.
两个生成器都使用命令来构建您的站点。
For Jekyll, use jekyll build. See .
对于Jekyll，请使用jekyll build 。 查看 。
For Hugo, use hugo. You can run hugo help or see .
对于雨果，用hugo 。 您可以运行hugo help或查看 。
You’ll have to choose the source for your GitHub Pages site. Once done, your site will update each time you push a new build. Of course, you can also automate your GitHub Pages build using GitHub Actions. Here’s one for , and one for .
您必须选择GitHub Pages网站的来源。 完成后，您每次推送新版本时，您的网站都会更新。 当然，您也可以使用GitHub Actions自动执行GitHub Pages构建。 这是一个 ，另一个是一起 。
All the substantial differences between these two generators are under the hood. All the same, let’s take a look at the finished themes, in two color variations.
这两个发电机之间的所有实质性差异都在引擎盖下。 都是一样，让我们看一下完成的主题，有两种颜色。
Here’s Hugo:
这是雨果：
Here's Jekyll:
这是杰基尔：
🤷
🤷
Both Hugo and Jekyll have their quirks and conveniences.
雨果和杰基尔都有自己的怪癖和便利。
From this developer’s perspective, Jekyll is a workable choice for simple sites without complicated organizational needs. If you’re looking to render some one-page posts in an and host with GitHub Pages, Jekyll will get you up and running fairly quickly.
从开发人员的角度来看，对于没有复杂组织需求的简单站点，Jekyll是一个可行的选择。 如果您希望以呈现一些一页的文章并通过GitHub Pages托管，Jekyll将使您起步并快速运行。
Personally, I use Hugo. I like the organizational capabilities of its Page Bundles, and it’s backed by a dedicated and conscientious team that really seems to strive to facilitate convenience for their users. This is evident in Hugo’s many functions, and handy tricks like and . They seem to release new fixes and versions about as often as I make a new cup of coffee - which, depending on your use case, may be fantastic, or annoying.
我个人使用雨果。 我喜欢它的Page Bundles的组织功能，并且它有一个敬业而认真的团队的支持，这个团队似乎确实致力于为用户提供便利。 这在Hugo的许多功能以及诸如和类的便捷技巧中就很明显。 他们似乎发布新补丁和版本的频率与我喝一杯新咖啡的频率差不多-根据您的用例，这可能很棒或令人讨厌。
If you still can’t decide, don’t worry. The I created is available for both Hugo and Jekyll. Start with one, switch later if you want. That’s the benefit of having options.
如果您仍然不能决定，请不要担心。 我创建的可用于Hugo和Jekyll。 从一个开始，然后根据需要切换。 那就是拥有选择权的好处。
翻译自:
转载地址：http://nhgwd.baihongyu.com/